React Native 运行时（React Native）

概览（Overview）

新版 React Native Runtime 已发布，包名为 @rive-app/react-native（基于 Nitro Modules），推荐新项目优先使用。

相关资源：

• GitHub：https://github.com/rive-app/rive-nitro-react-native
• NPM：https://www.npmjs.com/package/@rive-app/react-native
• 迁移指南：/docs/Runtimes/React Native/Migration Guide

环境要求（新版）

• React Native：0.78+
• Expo SDK：53+
• iOS：15.1+
• Android：SDK 24+
• Xcode：16.4+
• JDK：17+
• react-native-nitro-modules：0.25.2+

快速开始（Quick Start）

1) 安装依赖

npm install @rive-app/react-native react-native-nitro-modules
# 或
yarn add @rive-app/react-native react-native-nitro-modules

2) 加载文件并渲染

import { View } from 'react-native';
import { RiveView, useRiveFile, Fit } from '@rive-app/react-native';

export default function Demo() {
  const { riveFile } = useRiveFile(require('./assets/demo.riv'));

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      {riveFile && (
        <RiveView
          file={riveFile}
          fit={Fit.Contain}
          style={{ width: 320, height: 320 }}
        />
      )}
    </View>
  );
}

3) 通过 ref 控制播放

import { useRive, RiveView } from '@rive-app/react-native';

const { riveViewRef, setHybridRef } = useRive();

<RiveView hybridRef={setHybridRef} file={riveFile} />

riveViewRef?.play();
riveViewRef?.pause();

关键能力

• 文件加载：useRiveFile（支持 require/URL/resource name/ArrayBuffer）
• 视图控制：useRive + RiveView + ref methods
• 数据绑定：useViewModelInstance + useRiveNumber / useRiveTrigger 等 hooks

Legacy 说明

Legacy 包 rive-react-native 仍可用，但建议逐步迁移到新版包以获得更好性能与能力。

Expo 接入可参考：

• /docs/Runtimes/React Native/Adding Rive to Expo